Webhooks

Presence Sync ruft bei Statusübergängen hinterlegte HTTP(S)-Endpunkte auf und meldet den Präsenzwechsel eines Benutzers damit aktiv an Drittsysteme — Ihr System muss weder die STARFACE noch Microsoft Graph abfragen. Typische Empfänger sind Raumbuchungs- und Türschildsysteme, Wallboards und Automatisierungsplattformen. Die Gegenstelle benötigt lediglich einen per HTTP oder HTTPS erreichbaren Endpunkt, der GET- oder POST-Aufrufe entgegennimmt.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: ausgehender HTTP(S)-Aufruf; das Modul ist Client, Ihr System stellt den Endpunkt bereit
• Richtung: STARFACE (Modul) → Drittsystem; ausgelöst ausschließlich durch die Synchronisationsrichtung Microsoft → STARFACE
• Konfigurationsort: je Synchronisationsregel in der Moduloberfläche (siehe unten)
• Anzahl: beliebig viele Webhooks je Regel
• Methoden: GET oder POST (Auswahl in der Oberfläche)
• URL: http:// oder https://; enthält die Platzhalter
• Header und Body: nicht konfigurierbar; Aufrufe werden ohne Body gesendet (Details unten)
• Authentifizierung: keine dedizierte — ein Geheimnis (etwa ein Token) lässt sich als Bestandteil der URL hinterlegen, z. B. als Query-Parameter
• Antwort: wird nicht ausgewertet; HTTP-Statuscode und -Meldung erscheinen nur im Modul-Log
• Verfügbar seit: Modulversion 23.4.5

Auslösezeitpunkt

Das Modul fragt die Microsoft-Präsenz der ausgewählten Benutzer zyklisch ab (Synchronisationsläufe im Abstand von etwa zwei Sekunden). Die Webhooks einer Regel feuern, wenn ein Benutzer in die Statuskombination dieser Regel wechselt — also genau dann, wenn der Abgleich eine Änderung gegenüber dem letzten Lauf feststellt und für die neue Kombination aus Verfügbarkeit und Aktivität eine Regel existiert. Sie feuern je Benutzer und Übergang einmal; ein unveränderter Status löst keine weiteren Aufrufe aus.

Voraussetzungen sind dieselben wie für den Präsenzabgleich insgesamt: aktivierte Synchronisation innerhalb der konfigurierten Synchronisationszeiten, eine gültige Microsoft-Anmeldung sowie ein Benutzer, der zur ausgewählten Zielmenge gehört, vom Lizenzumfang abgedeckt ist und den Abgleich nicht per UCC-Integration für sich deaktiviert hat. Ein Sonderfall wird bewusst unterdrückt: Setzt die Rücksynchronisation den Microsoft-Status wegen eines laufenden STARFACE-Telefonats selbst auf „Beschäftigt / Im Gespräch", feuern die Webhooks für dieses Echo nicht.

Die Aufrufe laufen asynchron und parallel — jeder Webhook in einem eigenen Thread. Das Modul wartet nicht auf Antworten; die übrigen Aktionen der Regel (Chat-Status, DND, Gruppen, Endgeräte) werden unabhängig vom Ausgang der Aufrufe umgesetzt.

Konfiguration

Webhooks werden je Synchronisationsregel hinterlegt: Moduloberfläche, Tab Einstellungen, Karte Synchronisationseinstellungen. Jede Zeile der Regelmatrix steht für eine Kombination aus Microsoft-Verfügbarkeit und -Aktivität; die Schaltfläche in der Spalte Webhooks öffnet den Dialog „Webhooks konfigurieren" der jeweiligen Regel. Dort legen Sie je Eintrag Request-Methode (GET oder POST) und URL fest und fügen über die Plus-Schaltfläche weitere Webhooks hinzu. Die Oberfläche prüft die URL auf das Schema http:// bzw. https://; Einträge ohne URL werden beim Abgleich übersprungen. Grundlagen zur Regelmatrix beschreibt die Dokumentation.

Folgende Regeln (Statuskombinationen) stehen zur Verfügung:

Verfügbarkeit	Aktivitäten
Verfügbar (Available)	Verfügbar (Available)
Abwesend (Away)	Abwesend (Away)
Bin gleich zurück (BeRightBack)	Bin gleich zurück (BeRightBack)
Beschäftigt (Busy)	Beschäftigt (Busy) · Im Gespräch (InACall) · Im Gespräch (Konferenz) (InAConferenceCall) · In einer Besprechung (InAMeeting)
Nicht stören (DoNotDisturb)	Nicht stören (DoNotDisturb) · Präsentieren (Presenting)
Offline (Offline)	Offline (Offline) · Status unbekannt (PresenceUnknown) · Außer Haus (OffWork)
Status unbekannt (PresenceUnknown)	Status unbekannt (PresenceUnknown)

Die Kombinationen entsprechen den Werten, die Microsoft Graph als availability und activity der Präsenz liefert.

Methoden, Header und Body

Die Oberfläche bietet die Request-Methoden GET und POST an. Eigene HTTP-Header lassen sich nicht hinterlegen; der Aufruf wird ohne zusätzliche Kopfzeilen abgesetzt. Ein Request-Body ist über die Oberfläche derzeit nicht konfigurierbar — POST-Aufrufe werden ohne Body gesendet, alle Nutzdaten reisen in der URL. Das Datenmodell des Moduls sieht darüber hinaus bereits die Methoden PUT und DELETE sowie ein Body-Feld vor (ein gesetzter Body würde mit Content-Type: application/json übertragen); in der Oberfläche sind diese Felder nicht freigeschaltet.

Platzhalter

In der URL ersetzt das Modul beim Aufruf die folgenden Platzhalter durch die Daten des STARFACE-Benutzers, dessen Statuswechsel den Webhook ausgelöst hat. Die Ersetzung ist eine reine Zeichenkettenersetzung: Die Werte werden nicht URL-kodiert eingesetzt (relevant bei Umlauten oder Leerzeichen, etwa in Nachnamen), und unbekannte {…}-Ausdrücke bleiben unverändert in der URL stehen. Platzhalter sind an jeder Stelle der URL zulässig — im Pfad ebenso wie in Query-Parametern.

Benutzerdaten

Platzhalter	Bedeutung	Beispielwert
{email}	E-Mail-Adresse des STARFACE-Benutzers (zugleich der Zuordnungsschlüssel zum Microsoft-Konto)	m.mustermann@example.com
{sfAccountId}	Interne Account-ID des Benutzers auf der STARFACE (numerisch)	1042
{sfLoginId}	Login-ID des Benutzers	33
{sfLastName}	Nachname des Benutzers	Mustermann
{sfFirstName}	Vorname des Benutzers	Max

Zielstatus

Einen Platzhalter für den Zielstatus gibt es nicht — er ist auch nicht nötig: Da Webhooks je Regel hinterlegt werden, steht der Status bereits durch die auslösende Regel fest. Hinterlegen Sie ihn statisch in der URL des jeweiligen Webhooks, etwa als Query-Parameter state=busy in der Regel „Beschäftigt" und state=free in der Regel „Verfügbar".

Beispiele

Türschild per GET ansteuern

Ein Raumbuchungssystem soll das Türschild eines Mitarbeiters auf „belegt" schalten, sobald er in Microsoft Teams in eine Besprechung wechselt — und wieder freigeben, wenn er verfügbar ist. Dazu erhalten zwei Regeln je einen Webhook mit statischem Statusparameter:

Regel	Methode	URL
Beschäftigt / In einer Besprechung	GET	https://raumbuchung.example.com/api/presence?user={email}&state=busy
Verfügbar / Verfügbar	GET	https://raumbuchung.example.com/api/presence?user={email}&state=free

Wechselt der Benutzer Max Mustermann in eine Besprechung, setzt das Modul folgenden Aufruf ab:

GET https://raumbuchung.example.com/api/presence?user=m.mustermann@example.com&state=busy

Fachanwendung per POST benachrichtigen

Eine Automatisierungsplattform (etwa für ein Wallboard) nimmt Statusmeldungen über einen Webhook-Endpunkt entgegen. Der Zielstatus steht im Query-Parameter event, die Benutzerzuordnung erfolgt über die Account-ID; ein Zugriffstoken ist als Query-Parameter Teil der URL:

Regel	Methode	URL
Nicht stören / Präsentieren	POST	https://automation.example.com/hooks/starface-presence?event=presenting&sfAccountId={sfAccountId}&lastName={sfLastName}&token=8f3a91

Der resultierende Aufruf wird ohne Body gesendet:

POST https://automation.example.com/hooks/starface-presence?event=presenting&sfAccountId=1042&lastName=Mustermann&token=8f3a91

Anwendungsbeispiel

Ein Contact-Center-Wallboard zeigt neben den Warteschlangen auch, welche Fachexperten gerade ansprechbar sind. Presence Sync meldet jeden Wechsel auf „Beschäftigt" oder „Verfügbar" per Webhook an das Wallboard — die Teamleitung sieht ohne Nachfragen, wen sie für eine Eskalation erreichen kann.

Fehlerbehandlung

• Ein Zustellversuch, keine Wiederholungen: Jeder Statusübergang löst genau einen Aufruf je Webhook aus. Schlägt er fehl, wird er nicht wiederholt; der nächste Aufruf erfolgt erst beim nächsten passenden Statusübergang. Ihr Empfänger sollte den zuletzt gemeldeten Zustand daher als maßgeblich behandeln.
• Fehler bleiben lokal: Ein fehlgeschlagener Aufruf (Empfänger nicht erreichbar, DNS-/TLS-Fehler, ungültige URL nach der Platzhalterersetzung) wird im Modul-Log protokolliert und beeinträchtigt weder die übrigen Webhooks der Regel noch den Präsenzabgleich selbst.
• HTTP-Statuscodes werden nicht ausgewertet: Auch eine 4xx-/5xx-Antwort gilt nicht als Fehler. Statuscode und -meldung der Antwort erscheinen ausschließlich im Modul-Log (Log-Level Trace).
• Timeouts: Das Modul setzt keine eigenen Verbindungs- oder Lese-Timeouts; es gelten die Standardwerte der Java-Laufzeitumgebung der STARFACE. Da jeder Aufruf in einem eigenen Thread läuft, verzögert ein langsamer Empfänger den Abgleich nicht.
• Diagnose: Auf Log-Level Trace protokolliert das Modul je Aufruf die URL-Vorlage, die ersetzte URL, die Methode sowie Response-Code und -Meldung. Aktivieren Sie Trace nur temporär zur Analyse und setzen Sie das Log-Level anschließend zurück.

Versionierung & Kompatibilität

Die Schnittstelle ist nicht explizit versioniert. Den stabilen Vertrag bilden die fünf Platzhalternamen, die Auslösung je Regel beim Statusübergang sowie die Aufrufform (GET/POST ohne Body); Änderungen und Erweiterungen dokumentieren die Release Notes der jeweiligen Modulversion. Webhooks stehen seit Modulversion 23.4.5 zur Verfügung. Die Statuskombinationen der Regeln folgen den von Microsoft Graph gelieferten Präsenzwerten (availability/activity); die im Datenmodell vorbereiteten, derzeit nicht freigeschalteten Felder (PUT/DELETE, Request-Body) können in künftigen Versionen aktiviert werden — maßgeblich sind auch hier die Release Notes.